2026 09 06 Astra 전환 AGENTS.md·Skills 감사 보고서

📅 2026-09-06 11:20 · obsidian-share

title: Astra 전환 AGENTS.md·Skills 감사 보고서

type: note

status: audited

source_type: local-audit

knowledge-candidate: true

created: 2026-09-06

updated: 2026-09-06

topics:

- GPT-6 Astra

- Codex

- AGENTS.md

- Skills

- Prompt engineering

- Local configuration audit

keywords:

- trigger scope

- instruction bloat

- progressive disclosure

- plugin cache

- read-only audit

source:

- "2026-09-06 Astra 최근 논의와 대비 전략.md"

Astra 전환 AGENTS.md·Skills 감사 보고서

한 줄 요약

현재 디오 환경에서 즉시 손댈 대상은 프로젝트 AGENTS.md가 아니라, 모든 코딩 작업·모든 응답에 가까운 범위로 작동할 수 있는 ponytail과 범용 콘텐츠 요청까지 자동 호출할 수 있는 notebooklm의 트리거 범위다. 나머지는 삭제보다 유지·관찰·작은 테스트가 우선이다.

감사 범위와 원칙

  • 감사일: 2026-09-06
  • 대상:

    • - /Users/macmini/ai-creator-bus-site/AGENTS.md

    - /Users/macmini/dio-ai-talktalk-site/AGENTS.md

    - /Users/macmini/.codex/AGENTS.md

    - /Users/macmini/.agents/skills/*/SKILL.md

    - Codex 내부 플러그인 영역에서 발견된 AGENTS.md

  • 방식: 파일 내용 읽기, 메타데이터 파싱, 크기·라인 수·description·중복 이름·광범위 트리거 점검
  • 이번 단계의 제한: 기존 AGENTS.md와 SKILL.md는 수정·삭제하지 않음

    • 1. 전체 현황

    1-1. Skills

  • SKILL.md: 74개
  • 전체 크기: 약 469KB
  • 전체 분량: 11,092줄
  • 모든 Skill에 name과 description이 있음
  • 중복된 Skill 이름 없음
  • description 300자를 넘는 Skill: 3개
  • description 500자를 넘는 Skill: 0개
  • 본문 10,000자를 넘는 Skill: 2개
  • description에 must/always/never/only/required 같은 강한 표현이 있는 Skill: 10개

    • 숫자 자체는 문제로 보지 않는다. Skill 본문은 필요할 때 읽는 구조라서, Astra 대비에서 중요한 것은 총량보다 description이 어떤 작업에 Skill을 호출하게 만드는지와 본문에 전역 행동을 강제하는 문장이 있는지다.

    1-2. 프로젝트 `AGENTS.md`

    AI NOOK

    경로: /Users/macmini/ai-creator-bus-site/AGENTS.md

  • 44줄, 1,794바이트
  • 브랜드명·색상·독자 관점·카드 구조·발행 절차를 명확히 정의
  • 절대, 금지, 반드시가 있지만 색상·독자·발행 승인처럼 실제로 지켜야 할 브랜드 기준에 사용됨
  • 전체 저장소를 무조건 읽으라는 규칙이나 불필요한 실행 절차는 보이지 않음

    • 판정: 유지

    이 파일은 모델이 일반 지식만으로 알아낼 수 없는 프로젝트 고유 정보다. Astra 대응을 이유로 줄이면 오히려 브랜드 결과물이 흔들릴 가능성이 크다.

    AI 톡톡

    경로: /Users/macmini/dio-ai-talktalk-site/AGENTS.md

  • 50줄, 1,639바이트
  • 표지 브랜드·색상·독자 난이도·톤·콘텐츠 비율·발행 일정·배포 경로를 정의
  • 절대, 금지, 반드시가 일부 있지만 모두 브랜드·발행 품질 경계에 해당함
  • 전체 프로젝트 사전 탐색이나 매 단계 승인처럼 작업을 과도하게 막는 규칙은 보이지 않음

    • 판정: 유지

    전역 Codex 지침

    경로: /Users/macmini/.codex/AGENTS.md

  • 현재 0바이트 빈 파일

    • 판정: 변경 없음

    여기에 규칙을 새로 채우는 것이 지금의 Astra 대비책은 아니다. 전역 규칙은 모든 프로젝트에 영향을 주므로, 실제 반복 문제와 권한 경계를 먼저 확인한 뒤 별도 설계해야 한다.

    2. 우선순위별 판정

    P0 — 트리거 범위를 먼저 줄일 후보

    `ponytail`

    경로: /Users/macmini/.agents/skills/ponytail/SKILL.md

    현재 확인된 내용:

  • description에서 “ANY coding task”에 사용하라고 함
  • 본문에 “ACTIVE EVERY RESPONSE”라고 되어 있음
  • 코딩 작업뿐 아니라 리팩터링·리뷰·설계·라이브러리 선택까지 폭넓게 개입
  • 기본 강도가 full이며, 세션 동안 지속된다고 설명

    • 판정: 축약 + 명시적 호출로 제한

    이 Skill은 “간단하게 만들자”는 좋은 원칙을 담고 있지만, Astra처럼 지침을 더 강하게 따르는 모델에서는 다음 문제가 생길 수 있다.

  • 사용자가 단순히 코딩 작업을 요청했을 뿐인데 항상 ponytail이 개입할 수 있음
  • 사용자가 원한 충분한 설명·테스트·구조화를 “과잉”으로 판단할 수 있음
  • AGENTS.md나 다른 Skill의 지침과 충돌할 때 삭제·축약을 우선할 수 있음
  • “모든 응답에 활성”이라는 표현이 다른 지침보다 우선되는 것처럼 해석될 수 있음

    • 권장 방향:

    name: ponytail
description: Use when the user explicitly asks for ponytail, YAGNI, the simplest solution, or minimal implementation. Do not activate automatically for ordinary coding tasks.

    본문도 다음 방향으로 바꾸는 것이 안전하다.

  • ACTIVE EVERY RESPONSE 삭제
  • “이 Skill을 명시적으로 호출한 작업에서만 적용”으로 변경
  • 사용자가 요구한 기능·검증·설명을 임의로 줄이지 않는다는 우선순위 추가
  • 안전·정확성·사용자 요구가 단순성보다 우선이라는 문장을 상단에 배치

    • 지금은 실제 수정하지 않고 후보로만 남긴다.

    P1 — 자동 호출 범위와 본문 크기를 함께 검토할 후보

    `notebooklm`

    경로: /Users/macmini/.agents/skills/notebooklm/SKILL.md

    현재 상태:

  • 593줄, 28,268바이트
  • description 265자
  • NotebookLM 명시 호출뿐 아니라 다음과 같은 일반 표현에도 활성화될 수 있음:

    • - “이 자료로 팟캐스트 만들어줘”

    - “이 URL들을 요약해줘”

    - “퀴즈 만들어줘”

    - “영상 설명 만들어줘”

  • 본문에는 인증·프로필·병렬 실행·노트 저장·다운로드·생성·삭제 절차가 모두 포함됨
  • 삭제·생성·다운로드·노트 저장은 확인을 요구하는 구조가 이미 있어 안전장치는 양호함

    • 판정: description 트리거 축소, 본문은 references 분리 검토

    위험은 본문이 긴 것 자체가 아니라, NotebookLM을 명시하지 않은 일반 콘텐츠 요청까지 자동으로 가져갈 수 있다는 점이다. 특히 오디오·영상·요약·퀴즈는 다른 미디어·콘텐츠 Skill과 겹칠 수 있다.

    권장 description 방향:

    name: notebooklm
description: Use when the user explicitly mentions NotebookLM or asks to add sources, query a NotebookLM notebook, or generate/download an artifact from an existing NotebookLM notebook. Do not activate for generic summaries, podcasts, quizzes, or videos without NotebookLM context.

    본문 구조는 다음처럼 나누는 것이 좋다.

  • SKILL.md: 활성 조건, 안전 경계, 최소 실행 흐름
  • references/auth.md: 로그인·프로필·병렬 실행
  • references/artifacts.md: 오디오·비디오·리포트·퀴즈·슬라이드
  • references/commands.md: 전체 명령 레퍼런스
  • references/safety.md: 삭제·다운로드·노트 저장 확인 규칙

    • P1 — description은 길지만 현재 경계가 좋은 Skill

    `orca-cli`

    경로: /Users/macmini/.agents/skills/orca-cli/SKILL.md

  • description 706자
  • Orca 관리 상태와 일반 데스크톱·브라우저 상태를 구분함
  • orchestration, computer-use와의 역할 분담도 description에 명시됨
  • 본문은 실제 사용법을 orca 바이너리에서 읽도록 한 discovery stub 구조

    • 판정: 유지

    긴 이유가 단순한 장황함이 아니라 도구 선택 경계 때문이다. 무리하게 줄이면 orca-cli와 orchestration과 computer-use가 다시 충돌할 수 있다. 다만 실제 오호출 사례가 생기면 세 Skill의 경계 문장만 함께 조정한다.

    `orchestration`

    경로: /Users/macmini/.agents/skills/orchestration/SKILL.md

  • description 813자
  • “구조적 멀티에이전트 조정”과 “단순 handoff/터미널 제어”를 분리함
  • orca-cli와의 선택 기준이 명확함

    • 판정: 유지

    현재는 Astra 시대에 필요한 “얇은 라우터 + 필요한 경우에만 상세 가이드 로드”에 가까운 구조다.

    `computer-use`

    경로: /Users/macmini/.agents/skills/computer-use/SKILL.md

  • description 531자
  • 로컬 데스크톱·브라우저·웹뷰 UI를 담당하고 Orca 내부 브라우저와의 경계를 설명함

    • 판정: 유지·관찰

    orca-cli와 기능상 인접하지만, 현재 description에는 “Orca 내부 상태는 Orca, 그 밖의 데스크톱 UI는 Computer Use”라는 구분이 있어 당장 통합할 이유가 없다.

    P2 — 길지만 즉시 줄일 필요가 없는 Skill

    `k-dart`

  • 416줄, 16,297바이트
  • 금융 공시 조회라는 도메인 특성상 API·필드·검증 절차가 많을 수 있음

    • 판정: 유지, 필요 시 references 분리

    `corporate-registration-consulting`

  • 128줄, 13,262바이트
  • 법인등기 절차는 누락이 위험하므로 길이만으로 줄이지 않음

    • 판정: 유지, 실제 반복 사용 후 분리 검토

    `korean-scholarship-search`, `delivery-tracking`, `rhwp-edit` 등

    도메인 API와 예외 처리가 많은 Skill은 본문 크기보다 다음을 먼저 본다.

  • description이 특정 작업으로 한정되어 있는가
  • 인증·결제·삭제·저장에 대한 확인 경계가 있는가
  • 상세 절차가 필요할 때만 로드되는가

    • 판정: 삭제하지 않고 사용 사례가 쌓인 뒤 분리

    3. 중복과 충돌 점검

    3-1. 이름 중복

    74개 Skill에서 중복된 name은 확인되지 않았다.

    3-2. nearby Skill 묶음

    다음 Skill들은 현재 위치를 묻고 공식 데이터로 조회한다는 공통 문장을 공유한다.

  • cheap-gas-nearby
  • public-restroom-nearby
  • blue-ribbon-nearby
  • parking-lot-search
  • kakao-bar-nearby

    • 판정: 유지

    공통 문장 때문에 description 토큰은 비슷하지만, 각 Skill의 핵심 명사인 주유소·화장실·맛집·주차장·술집이 구분된다. 합치면 오히려 라우팅이 나빠질 가능성이 있다.

    개선한다면 각 description의 첫 문장을 핵심 명사로 시작한다.

    Use for nearby parking-lot searches...
Use for nearby public-restroom searches...
Use for nearby gas-station searches...

    3-3. `paseo-*` 묶음

    paseo, paseo-help, paseo-advisor, paseo-committee, paseo-handoff, paseo-loop는 같은 제품을 다루지만 역할이 나뉘어 있다.

    판정: 유지·실제 오호출만 기록

    현재 단계에서 하나로 합치기보다, 다음 작업에서 잘못 선택된 사례가 2~3회 쌓일 때 description을 좁히는 것이 낫다.

    4. Codex 플러그인 영역의 `AGENTS.md`

    재귀 검색 결과, 사용자 프로젝트 밖에서 다음 파일들이 추가로 확인됐다.

    사용자 설정에 가까운 영역

  • /Users/macmini/.codex/plugins/cache/openai-bundled/sites/0.1.43/AGENTS.md

    • - 922바이트

    - Sites 플러그인의 미러 파일 동기화 규칙

    이 파일은 플러그인 캐시의 일부로 보이며, 직접 수정하면 다음 업데이트에서 덮어써질 수 있다.

    판정: 수정하지 않음

    임시 플러그인 영역

  • /Users/macmini/.codex/.tmp/plugins/plugins/build-web-apps/skills/react-best-practices/AGENTS.md

    • - 94,496바이트, 3,373줄

    - Vercel React/Next.js 성능 가이드 전체 문서

  • /Users/macmini/.codex/.tmp/plugins/plugins/build-web-apps/skills/supabase-best-practices/AGENTS.md

    • - 2,160바이트, 67줄

    - Supabase Skill의 탐색·참조 안내

  • /Users/macmini/.codex/.tmp/plugins/plugins/zoom/AGENTS.md

    • - 463바이트, 12줄

    - Zoom 플러그인 범위 설명

    react-best-practices/AGENTS.md는 일반 프로젝트 규칙이라기보다 플러그인 내부의 대형 참조 문서다. 다만 파일명이 AGENTS.md라서 Codex가 이 디렉터리에서 실행될 경우 instruction discovery 대상이 될 수 있고, 94KB는 일반적인 instruction 문서 한도를 크게 넘는다.

    판정: 사용자 파일을 수정하지 말고 업스트림·플러그인 구조 이슈로 관리

    권장 방향:

  • 플러그인 내부에서는 큰 문서를 references/ 아래로 이동
  • 루트 SKILL.md 또는 짧은 AGENTS.md에는 라우팅과 읽기 조건만 남김
  • 실제 플러그인 저장소에서 수정해야 하며, 로컬 캐시 파일을 직접 편집하지 않음
  • 해당 플러그인 작업을 실제로 수행하는 경우에만 영향 여부를 별도 테스트

    • 5. 별도 운영 이슈

    agent-reach Skill과 CLI 설치 상태 불일치

  • /Users/macmini/.agents/skills/agent-reach/SKILL.md는 존재함
  • 그러나 agent-reach doctor --json 실행 파일은 현재 PATH에서 찾지 못함
  • /Users/macmini/.agent-reach-venv/는 존재하지만 해당 가상환경에 agent_reach 모듈과 실행 파일이 보이지 않음

    • 판정: Astra 리팩터링과 별개의 설치·운영 이슈

    이 상태에서는 Skill이 요구하는 공식 라우터 명령을 실행할 수 없고, 웹 조사 시 직접 추출·검색으로 우회하게 된다. 나중에 정리할 때는 Skill을 먼저 고치기보다 설치 문서와 실제 CLI 제공 경로를 확인해야 한다.

    6. 권장 실행 순서

    지금 바로 할 일

    1. ponytail을 명시적 호출 전용으로 바꿀지 결정

    2. notebooklm description을 NotebookLM 명시 맥락 전용으로 좁힐지 결정

    3. 기존 AI NOOK·AI 톡톡 AGENTS.md는 그대로 유지

    4. 플러그인 임시·캐시 영역은 건드리지 않음

    다음 테스트

    동일한 3개 작업을 현재 설정에서 실행하고 기록한다.

    1. 일반 코드 수정

    2. 브랜드 프로젝트의 카드뉴스 수정

    3. NotebookLM과 무관한 일반 문서 요약

    각 작업에서 확인할 것:

  • 의도하지 않은 Skill이 호출됐는가
  • ponytail이 자동으로 개입했는가
  • NotebookLM이 일반 요약 작업을 가로챘는가
  • AGENTS.md를 과도하게 읽고 시작이 늦어졌는가
  • 사용자가 요구한 검증·설명·완료 기준을 임의로 줄였는가

    • 수정 원칙

  • 삭제보다 description·트리거 범위 축소를 먼저 한다.
  • 사용자 프로젝트의 고유 규칙은 유지한다.
  • vendor/cache 파일은 직접 수정하지 않는다.
  • 한 번에 하나의 Skill만 바꾸고 같은 작업을 다시 실행한다.
  • 바꾸기 전 원본을 보존하고 되돌릴 수 있게 한다.

    • 최종 판정 목록

  • ai-creator-bus-site/AGENTS.md: 유지
  • dio-ai-talktalk-site/AGENTS.md: 유지
  • ~/.codex/AGENTS.md: 빈 상태 유지
  • ponytail/SKILL.md: P0 축약·명시 호출 전용 검토
  • notebooklm/SKILL.md: P1 description 축소·본문 분리 검토
  • orca-cli, orchestration, computer-use: 유지·오호출 관찰
  • 도메인형 대형 Skill: 유지·사용 사례 후 분리
  • nearby Skill 묶음: 유지·핵심 명사를 description 앞에 배치하는 개선만 검토
  • Codex 플러그인 캐시·임시 AGENTS.md: 직접 수정 금지
  • agent-reach CLI 설치 불일치: 별도 운영 이슈로 보류

    • 관련 노트

  • [[2026-09-06 Astra 최근 논의와 대비 전략]]
  • [[AI 파트너 진단 질문지]]
  • [[Anthropic Cybersecurity Skills 방어형 10개 Hermes 설치 및 사용법]]

    • 지식 후보 판단

    knowledge-candidate: true

    모델 업그레이드 때 설정을 무작정 지우지 않고, 트리거 범위·고유 지식·안전 경계·vendor 문서를 분리해 판단하는 재사용 가능한 감사 기준을 담고 있다.